<?xml version="1.0" encoding="UTF-8"?>
<!--

       Copyright 2006-2016 the original author or authors.

       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

       Unless required by applicable law or agreed to in writing, software
       distributed under the License is distributed on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.

-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Logging Information</title>
  <link rel="stylesheet" type="text/css" href="../mbgstyle.css" />
</head>
<body>
<h1>Logging Information</h1>
<p>MyBatis Generator (MBG) reports logging information in several different ways:</p>
<ul>
  <li>MBG may generate and display warning messages every time it is run.  These
      messages are meant to inform the user of significant events that may, or may not,
      require attention.  Examples are files being overwritten, non-fatal configuration errors, etc.
      Warnings are always displayed - regardless of configuration or command line options.</li>
  <li>MBG generates and may, or may not, display progress messages every time it is run.
      These messages are meant to inform to user of progress in code generation.  These messages
      are not displayed by default, but may be enabled by specifying the <code>-verbose</code>
      command line argument.  Or, if you are running MBG with the built in Ant task, these
      messages may be enabled by setting the <code>verbose</code> attribute to <code>true</code>,
      and then running Ant in verbose mode.</li>
  <li>Lastly, MBG will generate tracing (logging) messages for detailed debugging.
      This page explains how to enable these statements.</li>
</ul>

<p>In general, MBG will not repeat messages.  So if MBG generates a warning,
that warning is typically not also logged.  In some situations it may be useful
to enable logging as well as asking MBG to be verbose with progress messages.
This may generate a substantial output, but it will also give a very complete
picture of what's happening internally during the MBG run.</p>

<p>MBG will use Apache Log4J logging if Log4J is in the runtime classpath.
See <a href="http://logging.apache.org/log4j/">http://logging.apache.org/log4j/</a>
for more information about Log4J.  If Log4J is not in the runtime classpath,
MBG will use standard Java logging.</p>
<p>If for any reason you prefer to force the use of standard Java logging, even
if Log4J is in the runtime classpath, you may specify the <code>-forceJavaLogging</code>
command line argument, or specify the following line of code when running
MBG from Java:</p>
<p><code>org.mybatis.generator.logging.LogFactory.forceJavaLogging();</code></p>
<p><b>Important:</b> You should specify the above line of code <i>before</i> any other MBG code.</p>

<h2>Supplying an Alternate Implementation</h2>
<p>If you prefer to use a different logging implementation than Log4J or
standard Java logging, you may supply an alternate implementation of the key logging
interfaces as follows:</p>
<ol>
  <li>Create an implementation of the <code>org.mybatis.generator.logging.Log</code>
      interface that implements the key logging methods for you logging implementation
      of choice.</li>
  <li>Create an implementation of the <code>org.mybatis.generator.logging.AbstractLogFactory</code>
      interface that will return instances of your <code>Log</code> implementation.</li>
  <li>Configure MBG to use your new LogFactory by calling the method
      <code>org.mybatis.generator.logging.LogFactory.setLogFactory(AbstractLogFactory)</code>
      and supplying an instance of your <code>AbstractLogFactory</code> implementation.</li>
</ol>

<h2>Configuring Log4J Logging</h2>
<p>The following is a sample Log4J configuration file:</p>
<pre>
# Set root logger
log4j.rootLogger=INFO, A1

# A1 is set to be a ConsoleAppender.
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%-4r %-5p %c - %m%n

# MBG logging configuration...
log4j.logger.org.mybatis.generator=DEBUG
</pre>
<p>This file will instruct Log4J to write all MBG debug messages
to the console.  To use this file:</p>
<ol>
  <li>Create a file called <code>log4j.properties</code> in the
      root of your runtime classpath</li>
  <li>Copy the above entries into the new file</li>
  <li>Run MBG with the Log4J JAR file also in the runtime
      classpath.</li>
</ol>
<p>You should see many log messages in the console.</p>
<p>You may also configure Log4J in any of the other supported
methods if you prefer.</p>

<h2>Configuring Java Logging</h2>
<p>The following is a sample Java logging configuration file:</p>
<pre>
# Specify the handlers to create in the root logger
# (all loggers are children of the root logger)
handlers = java.util.logging.ConsoleHandler

# Set the default logging level for the root logger
.level = INFO

# Set the default logging level for new ConsoleHandler instances
java.util.logging.ConsoleHandler.level = ALL

# Set the default formatter for new ConsoleHandler instances
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

# Set the default logging level for the logger named org.mybatis.generator
org.mybatis.generator.level = FINE
</pre>
<p>This file will instruct Java to write all MBG debug messages
to the console.  To use this file:</p>
<ol>
  <li>Create a file called <code>logging.properties</code> (or any
     file name you prefer).  The file can exist anywhere in
     the file system (for example, in a <code>\temp</code> directory).</li>
  <li>Copy the above entries into the new file</li>
  <li>Run MBG with this VM argument:<br/>
    <code>-Djava.util.logging.config.file=\temp\logging.properties</code>
    (specify whatever actual file name and directory you used)
  </li>
</ol>
<p>You should see many log messages in the console.</p>
<p>You may also configure Java logging in any of the other supported
methods if you prefer.</p>

</body>
</html>
